Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/ACORNUSERS/CBSA/DISCUTIL/RECURSE.ZIP/!Recurse/!Help

Text File | 1998-04-05 | 13KB | 333 lines

If you are reading this help file in StrongED, you can use the ListOfFound
function with the "]" character to produce a clickable index to all the
headings in this file. Zap has a similar function, but I don't know the name.

]!Recurse v0.04
~~~~~~~~~~~~~~~

This is a utility which enables you to perform a specified action on a set
of files within a directory structure. You can, for example, load all HTML
files within a directory structure, or produce a text file of all jpeg files in
a browsers cache directory. Default options can be set, and it supports
a quiet mode to allow it to be run easily in boot sequences or from task alarms
as well as as a desktop utility.


]Requirements:
~~~~~~~~~~~~~~

Any Acorn machine running RiscOS 3.1 or greater, with at least 256Kb free
memory.

This application was written using WimpBasic by Clares, and so requires access
to !WBModules. This should be available for download from my website, as well
as from Clares, or from the WimpBasic support site. Just make sure that it has
been seen by the filer (on a RiscPC, just lob it into your Boot.Tasks
directory) and all should be well.

This program will create an index of known filetypes when it is first run. For
this reason I don't recommend running it from within an archive (and it won't
actually start from within an read-only archive). Decompress it before use.
Building the filetype list also requires access to !Scrap.


]Upgrading from an earlier version:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Copy the !Recurse application over the top of the earlier version. No option
settings will be changed by this, but you may want to check the options
window, and save the settings again (the format of the options file has
changed a bit). The Sprites file (not !Sprites) inside the !Recurse directory
is no longer required in v0.04, and can be deleted.


]Usage:
~~~~~~~

Run it, drag the directory you want to scan onto either the icon bar icon or
the window that opens, and select action from the menu. If you want to
restrict the scan so that it doesn't scan every file, then toggle the window
to full size, and select the appropriate options. Once ready to go, click on
"Start". The directory will be scanned, the action applied to matching files,
and at the end a little window will pop up telling you how many files were
matched, how many skipped, and other info. This window will close
automatically after 20 seconds, but can be closed manually.

The actions you can choose from are:

 Run    - Equivalent to double clicking on the file.
 Load   - Equivalent to shift+double clicking on the file.
 Delete - Fairly obviously, this deletes the file.
 List   - This generates a text file of matching filenames.
 Move   - This moves the files to a specified directory.

Some notes on each action:

]Run:
~~~~~
If you have chosen to run the files, you should be sure that the application
which handles that filetype can cope with multiple files - ChangeFSI for
example is a "one file at a time" application, and if sent a number of
files to process, will end up just processing the last one. There are
utilities such as BatchFSI and FSI_Batch which deal with this.Also, check that
the application doesn't load another copy of itself each time its files are
run - you can quickly use lots of memory this way.


]Load:
~~~~~~
The files are loaded as if they were text files - into your current editor.
You should be sure that the current editor can deal with the filetype you are
sending to it, and if loading binaries, you should be aware of the memory
requirements of loading a lot of them simultaneously.


]Delete:
~~~~~~~~
If you have the !Blackhole recycle bin loaded, then the files will be copied
there before deletion (See Options section to turn this off if required).

If you do not have !Blackhole running, or have disabled the option to use it,
you will be warned that the files are about to be deleted, and given a chance
to stop the process.


]List:
~~~~~~
A save box will pop up allowing you to specify where to save the listing. The
process will start when you click Ok on the save box. The list file also
contains the information displayed on the results window, as well other
settings that were used.


]Move:
~~~~~~
A save box will pop up allowing you to specify a directory to move the files
to. As with the list action, it will start when you click Ok on the save box.


]Restrictions on the scan:
~~~~~~~~~~~~~~~~~~~~~~~~~~

If you expand the main window to full size, you will see three rows of
options. By default these are all greyed out, which means that the scan
will match all files. The options are:

 Filetype
 Size
 Wildcard

The filetype option allows you to limit the search to any files matching a
specified type. It can also be set to match all files except a specified type.

The size option allows you to limit the search to any files larger or smaller
than a specified value. The value can be in bytes, Kilobytes, or Megabytes.
(Files exactly matching the value count as being larger, so strictly speaking
the options should be "Smaller" or "Equal to or Larger", but that would make
the window look untidy). A Kilobyte is taken as being 1024 bytes, and a
Megabyte is taken as being 1024 Kilobytes.

The wildcard option allows you to specify a standard RiscOS wildcard to match
the files against.

These options can be used together in any combination - some may be more useful
than others . . .


]The Filetype menu:
~~~~~~~~~~~~~~~~~~~

Because I've got no way of knowing what filetypes your machine knows about, the
first time !Recurse is run, it has a look at your machine, and generates a
list of known filetypes. This is kept in a text file called "Types" inside
the !Recurse directory. When it is run again, it just reads this file to
produce the filetype menu. On many machines, you may have far more types
registered than you want to appear on the menu, so you can edit this file
to reduce the number of items that appear on the list, or to give them more
descriptive names. Any line starting with a "#" character is a comment and is
ignored by the program. The format of the file is:

filetype : name of filetype

e.g
FFF : Text
FFE : Command
FFD : Data
etc

Blank lines, and lines that do not conform to the above format are ignored. The
key bit of information is the filetype number (in hex). The filetype name is
just the text that appears on the menu, and can be whatever you want that
filetype to be called. You can also alter the order of the items in this file
to put the filetype menu into whatever order you want.

In case you're interested, I taken a 'known' filetype to be one for which the
system variable file$type_xxx is set (xxx being the filetype in hex).

!Recurse is limited internally to a maximum of 256 filetypes in this list, but
Wimpbasic doesn't like creating menu's longer than 64 items long. For this
reason, I would recommend trimming the types file to 64 items or less . . .


]Options:
~~~~~~~~~

The options screen can be opened either from the program's menu, or by
adjust clicking on the icon bar icon. You can set:

The default settings for the main screen:
 The program will start with these options the next time it is run.

Imagefiles:
 If this is ticked, the program will treat imagefiles (ArcFS, Zip, X-Files etc)
 as if they were directories. If unticked, they are treated as files.

Use BlackHole:
 If ticked, and !Blackhole is running, then deletions will copy to the
 Blackhole bin directory before deleting. This has only been tested with
 BlackholeII v4.04, but should work with earlier versions.

Quiet Mode:
 If ticked, it enables Quiet Mode. See later.

Recurse Depth:
 This enables you to limit how far down a directory structure you want to go.
 Setting it to 0 will recurse unlimited directories.
 Setting it to 1 will only scan files in the directory that you dragged
 to the window/icon bar.
 Setting it to 2 will scan the directory, and sub-directories, but not
 sub-sub-directories.
 etc etc.

Rebuild Types:
 When clicked, Recurse will rescan your machine for known filetypes, and will
 rebuild the filetype menu. (i.e. you don't have to restart).
 For those who want to know, a "Known" filetype is one for which the system
 variable file$type_xxx has been set.

Quiet Mode:
 (Greyed out unless the Quiet Mode option is ticked)
 The default directory, listfile, and moveto directory can be specified here.

Choosing OK from the options screen sets the options for the currently
running program. Save saves them for the next time it is run, and Default
sets all options back to their default value. A backup of the options file is
kept with the name 'oldopts'.


]Quiet Mode:
~~~~~~~~~~~~

This is a completely silent mode that allows Recurse to be run during a boot
sequence or from a task alarm (from Alarm or Organiser). If the quiet mode
option is ticked, then when run it will apply the default action, filetype,
recursedepth etc to the directory specified in the options - Quiet Mode
section. If the default action is List, then the default list file is used
for output, likewise for the "move" action, the default move directory is used.
Recurse then shuts down.

In this version there is no way to disable Quiet Mode, other than manually
editting the Options file inside the Recurse application, and setting
quiet=False. This will be fixed in a later version.

The results window isn't displayed in quiet mode, and any warning messages
won't appear.


]Error Messages:
~~~~~~~~~~~~~~~~

None really, apart from the warning message before deletions take place. It
does check that !Scrap has been seen by the filer before starting though. If
it hasn't, it will warn you of this, and try to use a tmp directory inside its
own application directory. This may be important if including it in a boot
sequence, especially on pre RiscPC machines without the new Acorn boot
structure.


]Known Bugs:
~~~~~~~~~~~~

Fixed bugs: 8->
Version 0.02 had a bug when dealing with directory structures with more than
900 or so files in it. I think this is fixed (0.04 works with a test directory
structure of over 9000 files), but if you find problems with large structures,
get in touch by email.

One point to be aware of is that if you have it set to treat imagefiles as
directories (which it is by default), then the "Files Total" value may be
larger than the number of files reported by the filer's "count" option. The
filer (and !RealCount, if you are using it) treat imagefiles as files when
counting.

If you think you've found a bug in some other part of Recurse, send me an email
with the details.

This app has been tested on a RiscPC SA running RiscOS 3.70, and an a3010
running RiscOS 3.10.


]Future Improvements:
~~~~~~~~~~~~~~~~~~~~~

Check for hotkey on startup, and open options window if pressed:
 This is to allow you to turn off Quiet Mode without manually editing
 the options file.

Support for other Recycle bin programs:
 If anyone would like to suggest such programs, and how to detect that they
 are running, email me . . .

Proper multitasking, with a progress window. This would be especially useful
 when scanning slow filesystems, such as CD's.

Launch mailto and http from info window.

Option to retain dir structure on blackhole delete / move.
 Currently, files moved by Recurse are just moved into Blackhole, or the
 specified directory without their path relative to the recursed directory
 being preserved. If you have the same file name in two places in the
 structure, they would overwrite each other in the destination directory.
 You could also hit the limit on the number of files in a directory unless
 you have taken some action to prevent this (e.g. destination directory is an
 x-file.)


]Boring License bits:
~~~~~~~~~~~~~~~~~~~~

This application is Freeware. This means that you can copy it, distribute it as
much as you like with the following restrictions:

 - Only the complete application is distributed. Portions of this application
   may not be distributed either separately, or as part of another product.
 - It should not be distributed with an options file or a types file - it is
   designed to generate the types file for each machine it runs on.
 - No charge other than media and postage costs is made for this application.

I'd appreciate an email before you put it on a CD, cover disc, or the like, but
that's more a matter of courtesy, and of checking that you've got the latest
version . . .


]Web Resources:
~~~~~~~~~~~~~~~

The latest version of Recurse, together with anything else I may have
written in the meantime should be available from either:

http://www.pcweb.liv.ac.uk/mikejs/acorn.html
http://www.mike100.demon.co.uk/acorn.html

More information on WimpBasic, together with the latest version of !WBmodules,
(1.12 at time of writing this) is available at:

http://www.stcoll.ac.uk/clares
http://www.treknet.is/wb

--
5.4.98
Mike Sandells
mailto:[e-mail]
http://www.pcweb.liv.ac.uk/mikejs